Command:

To translate a DES or HMAC key  from encryption under a public key to encryption under the LMK. A signature over the encrypted key is verified if present

Notes:

This command requires the optional RSA licence, error code 67 will be returned if the command is not licenced.

Refer to the Key Type Table for key types and restrictions on key import.

See: Using the RSA cryptosystem for details of where valid values of the common parameters can be found.

Field

Length & Type

Details

COMMAND MESSAGE

Message header

m A

(Subsequently returned to the Host unchanged).

Command code

2 A

Value GI.

Encryption identifier

2 A

Identifier of the algorithm used to encrypt the DES key.

Pad Mode Identifier

2 N

Identifier of the Pad Mode used in the encryption process.

01 = PKCS#1 v1.5 method (EME-PKCS1-v1_5).

02 = OAEP (EME-OAEP-ENCODE).

Mask Generation Function

2 N

01 = MGF1 as defined in PKCS#1 v2.0.

Optional, only present if PAD Mode Identifier is 02 (OAEP).

MGF Hash Function

2 N

01 = SHA-1

Optional, only present if PAD Mode Identifier is 02 (OAEP).

This field defines the hash function to be used in the MGF.

OAEP Encoding Parameters Length

2 N

Optional, only present if PAD Mode Identifier is 02 (OAEP).

OAEP Encoding Parameters

n B

Optional, only present if PAD Mode Identifier is 02 (OAEP).

If present, this field should be encoded according to Reference 1 section 11.2.1. The HSM does not interpret or validate the contents of this field. If OAEP padding is used, but no Encoding Parameters are provided, then OAEP Parameters Length should be “00”, and this field will be empty.

OAEP Encoding Parameters Delimiter

1 A

“;”

Optional, only present if PAD Mode Identifier is 02 (OAEP).

Key Type

4 N

Key Type; used to indicate required LMK pair, including LMK variant.

For HMAC keys, Key Type should have the value 3401.

Delimiter

1 A

“=”
Only present if the following signature related fields are also present.

Signature Hash Identifier

2 N

Identifier of hash algorithm used to hash message.

Only present if Signature Indicator above is present.

Signature Identifier

2 N

Identifier of signature algorithm used to sign the message.

Only present if Signature Indicator above is present.

Signature Pad Mode Identifier

2 N

Identifier of the Pad Mode used in the signature process.

01 = PKCS#1 v1.5 method (EME-PKCS1-v1_5)

Only present if Signature Indicator above is present.

Encrypted Key Offset

4 N

Offset (in bytes) to first byte of encrypted key within the Data Block field.

Only present if Signature Indicator above is present.

Encrypted Key Length

4 N

Length (in bytes) of encrypted key within the Data Block field.

Only present if Signature Indicator above is present.

Signature Length

4 N

Length (in bytes) of the following Signature field.

Only present if Signature Indicator above is present.

Signature

n B

The signature which authenticates the encrypted key.

Only present if Signature Indicator above is present.

Delimiter

1 A

Delimiter, to indicate the end of the Signature field; value “;”

Only present if Signature Indicator above is present.

MAC

4 B

MAC on the following public key and authentication data, calculated using LMK pair 36-37.

Only present if Signature Indicator above is present.

Public Key

n B

Public key used to verify the supplied signature; DER ASN.1 format (sequence of modulus, exponent).

Only present if Signature Indicator above is present.

Authentication Data

n B

Optional; additional data included in the above MAC calculation (must not include “;”).

Only present if Signature Indicator above is present.

Delimiter

1 A

Delimiter, to indicate the end of the Authentication Data field; value “;”

Only present if Signature Indicator above is present

Data Block Length

4 N

Length (in bytes) of Data Block field.

Data Block

n B

The Data Block field consists of either:

The encrypted key, or
The signed data block containing the encrypted key.

Delimiter

1 A

Delimiter, used to indicate end of the Data Block field; value “;”

Private Key Flag

2 N

Flag to indicate location of the private key to decrypt the encrypted key;

if flag = 99 use private key provided with command

else flag = index of stored private key

Private Key Length

4 N

Length (in bytes) of the following field (only present if flag = 99)

Private Key

n B

Private key to decrypt the encrypted key, encrypted using LMK pair 34-35 (only present if flag = 99)

Delimiter

1 A

Delimiter, used to indicate end of the Private Key field; value “;”

Reserved

1 A

Ignored.

Only present if importing a DES key (i.e. Key Type <> 3401).

Key Scheme LMK

1 A

Key Scheme for imported key when encrypted under LMK.

Only present if importing a DES key (i.e. Key Type <> 3401).

Key Check Value Type

1 A

Key Check value calculation method:

0 = KCV backwards compatible

1 = KCV 6H

Only present if importing a DES key (i.e. Key Type <> 3401).

HMAC Hash Identifier

2 N

Identifier of the hash algorithm. Currently only SHA-1 is supported:

01 = SHA-1 HMAC

Only present if importing an HMAC key (i.e. Key Type = 3401).

HMAC Key Usage

2 N

01 = HMAC Generation

02 = HMAC Verification

03 = HMAC Generation and Verification

Only present if importing an HMAC key (i.e. Key Type = 3401).

HMAC Key Block Format

2 N

The format of the HMAC key block when stored encrypted under the LMK. The only value currently supported is 00.

Only present if importing an HMAC key (i.e. Key Type = 3401).

Delimiter

1 A

“=” 

Only present if Key Block Type follows:

Note: The “=” delimiter is used to distinguish from the normal “;” delimiter.

Key Block Type

2 N

01:  Key Block format supported in existing firmware.

02:  Key Block Template (format of template is specified below).

03:  Unformatted Key Block.

04:  ASN.1 Encoded Key Block.

Key Block Types 01, 02, 03 may be used for importing DES keys.

Key Block Types 02, 03, 04 may be used for importing HMAC keys.

Only present if the “=” delimiter above is present. When not present, the value of Key Block Type will be 01.

Key Block Template Length

4 N

Length of Key Block data

Only present if Key Block Type = 02.

Key Block Template

n H

Key Block, DER encoded in ASN.1 format. Key data zero filled.

Only present if Key Block Type = 02.

Delimiter

1 A

“;”

Only present if Key Block Type = 02.

Key Length

2 A

Length of the Key within the Key Block

Only present if Key Block Type is 02.

Key Offset

4 N

Offset to the location of the Key within the Key Block

Only present if Key Block Type = 02.

Check value length

1 N

Length in bytes of Check value field. Permitted values 0-8.

If no check value is supplied then this field will be 0.

If Check Value is supplied then the HSM will perform a validation check using the extracted key.

If Key Block Type = 02 then Check Value is expected at position indicated by Check Value Offset.

Only present when importing DES keys and if Key Block Type = 02.

Check value offset

4 N

Offset to the location of the check value within the Key Block. If Check Value length is 0 then this field is ignored.

Only present when importing DES keys and if Key Block Type = 02.

End Message Delimiter

1 C

Optional. Must be present if a message trailer is present. Value X'19

RESPONSE MESSAGE

Message header

m A

Returned to the Host unchanged.

Response code

2 A

Value GJ.

Error code

2 N

00 : No error

01 : MAC verification failure

02 : Signature verification failure

03 : Invalid secret key type

04 : Invalid secret key flag

05 : Invalid key type

06 : Invalid encryption identifier

07 : Invalid pad mode identifier

13 : LMK error; report to supervisor

15 : Error in input data

26 - Invalid Key Scheme

34 - Invalid HMAC hash identifier value

35 - Invalid HMAC key usage value

36 - Invalid HMAC key block format value

37 - Invalid HMAC key block type value

47 : DSP error; report to supervisor

49 : Secret key error; report to supervisor

50 : Public key does not conform to encoding             rules

51 : Invalid signature hash identifier

52 : Invalid signature identifier

53 : Invalid signature pad mode identifier

54 : Invalid Encrypted Key Offset

55 : Invalid Encrypted Key length

56 : Signature/Signature Length mismatch

57 : Invalid Key Check Value Type

67 : Command not licenced

74 : Invalid Digest Info syntax (no hash mode only)

76 : Key block length error

77 : Clear data block error

78 : Secret key length error

79 : Hash Algorithm Object Identifier error

80 : Data Block length error

81 : Invalid Key Block type

82 : Invalid check value length

83 : Key block format error

84 : Key block check value error

85 : Invalid OAEP Mask Generation Function

86 : Invalid OAEP MGF Hash Function

87 : OAEP Parameter Error

88 : OAEP Error

Initialization value

16 H

Initialization value for the DES key.

Optional. Only present if Key Block Type = 01.

Key (LMK)

16H or 32H
or
1A+32H or 1A+48H

Key, encrypted under LMK pair indicated by Key Type

Check Value

16 H
or

6 H

Check value on key. 16 H or 6 H depending upon the value of the Key Check Value Type field. 16 H if the Key Check Value Type field is absent.

Only present if Key Type is not 3401.

End Message Delimiter

1 C

Will only be present if present in the command message. Value X'19

Message Trailer

n A

Will only be present if in the command message. Maximum length 32 characters